home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / rbbsdocs.zip / RBBSDOCS.19 < prev    next >
Text File  |  1990-11-05  |  12KB  |  286 lines
  1.  
  2.  
  3.  
  4.     RBBS-PC QUESTIONNAIRE FACILITIES                                       19-1
  5.  
  6.  
  7.     19. RBBS-PC QUESTIONNAIRE FACILITIES
  8.     ------------------------------------
  9.     RBBS-PC  provides a  script-driven  questionnaire facility.   RBBS-PC  will
  10.     process a questionnaire when a  NEW caller logs in, before any  caller logs
  11.     off, or the user can select a questionnaire from  a menu.  To ask new users
  12.     questions  the file  named  in CONFIG  parameter  84 must  exist.   To  ask
  13.     questions  of users  when  they  say  G>oodbye the  file  named  in  CONFIG
  14.     parameter 85 must exist.  Questionnaires can also raise or lower the user's
  15.     security  level based on his/her  responses.  Answers  to the questionnaire
  16.     are appended to a file specified in each questionnaire script.
  17.  
  18.     RBBS-PC  will only activate the  corresponding script files  if they exist,
  19.     otherwise the functions are bypassed.
  20.  
  21.     The questionnaire script processor supports:
  22.  
  23.        - Branch to labels (forward and back branching)
  24.        - Display lines
  25.        - Display line and get response
  26.        - Response validation (Multiple choice)
  27.        - Numeric validation
  28.        - Raising and lowering user security level
  29.        - Aborting the questionnaire
  30.        - Chaining to another questionnaire
  31.        - Invoke a macro from within a questionnaire
  32.        - "Turbo" key can be turned on from within a questionnaire
  33.  
  34.     The first line in  every script file must  contain the file name where  the
  35.     responses to the script will be appended, and the maximum  security level a
  36.     user  can be  raised to.   The  rest  of each  script file  contains script
  37.     commands.  Script commands are 1 character  in length and must be in column
  38.     1 of each script line.
  39.  
  40.     Following is a list and description of valid script commands:
  41.  
  42.       :  A colon indicates a label command
  43.       *  An asterisk indicates a display data command
  44.       ?  A question mark indicates a display and wait for response command
  45.       =  An equal sign indicates a multiple choice branch command
  46.       >  A greater than symbol indicates a goto command
  47.       +  A plus sign indicates a raise security level command
  48.       -  A minus sign indicates a lower security level command
  49.       @  An "at" sign means to abort questionnaire and do not write results
  50.       &  An ampersand means to establish a questionnaire chain
  51.       T  The letter "T" turns on the "turbo" key mode
  52.       M  The letter "M" executes a "macro"
  53.       >  Assigns a value to a work variable
  54.  
  55.     CONFIG parameter 94 controls the maximum  number of work variables that can
  56.     be handled by questionnaires.
  57.  
  58.     RBBS-PC   questionnaires   even   support   "graphics"   versions   of  the
  59.     questionnaires.  Graphics  versions use the  standard convention of  ending
  60.     the  filename with "C" for color graphics  and "G" for ansi graphics.  E.g.
  61.     HLPRBBSC.DEF and HLPRBBSG.DEF are graphics versions of HLPRBBS.DEF.
  62.  
  63.  
  64.  
  65.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    19-2
  66.  
  67.  
  68.     19.1 Branching to Labels
  69.     ------------------------
  70.     :  Colon (Label command)
  71.        This command is used  to provide labels that can be branched to from =
  72.     and > commands.
  73.  
  74.               :QUESTION1
  75.  
  76.     Numeric labels are  not recommended because they  are easy to  confuse with
  77.     work  variables.   SmartText  variables will  be  interpreted as  such, eg.
  78.     ":-{FN"  will substitute  the  user's  first  name.    SmartText  and  Work
  79.     Variables are  dynamically substituted into  all questionnaire lines.   For
  80.     example,
  81.  
  82.               >-.[8].-
  83.  
  84.     will substitute the  value of work variable 8  for "[8]", so that if  8 has
  85.     "edit" as its value, it will go to the  label "-.edit.-".
  86.  
  87.     The ability to  get and substitute values,  and to have  graphics versions,
  88.     means that questionnaires  can support many of the features  of full screen
  89.     editing, including transmitting a template, then overlaying values into the
  90.     template.  An example that shows the power of questionnaires is
  91.  
  92.               ?29Change what field (1,2,...20)
  93.               ?[29]Change field [29]. from [[29]] to
  94.  
  95.     This asks which field to change and stores answer in work variable 29 (i.e.
  96.     value of work variable 29  is "7").    The second question then stores  the
  97.     answer  in the value  of work  variable 29, displays  the name  of the work
  98.     field being  changed, and then displays the old value of the work variable.
  99.     Suppose that the value  of work variable 7 is  "Yes".   Then the  series of
  100.     substitutions RBBS-PC makes into the second line before executing it are:
  101.  
  102.               ?7Change field [29]. from [[29]] to
  103.               ?7Change field 7. from [[29]] to
  104.               ?7Change field 7. from [7] to
  105.               ?7Change field 7. from Yes to
  106.  
  107.     19.2 Display Data Command
  108.     -------------------------
  109.     *  Asterisk (Display data command)
  110.        This  command is used  to send  data to the  user.   SmartText and Macro
  111.     commands are interpreted before display (see section 7.8).  "*/FL" will not
  112.     display the "/FL"  because it is  interpreted as a  macro command.  If  you
  113.     want to work  variables to overlay a display  template, keeping it's length
  114.     (e.g. for columnar display), put  "/FL" after the "*".  E.g.  if variable 1
  115.     has value "12345" and 2 has "abcdef", then
  116.  
  117.               */FL.[1]....[2]......
  118.  
  119.          will display ".12345..abcdef...", whereas
  120.  
  121.               *.[1]....[2]......
  122.  
  123.          will display ".12345....abcdef......".
  124.  
  125.     One of  the more useful capabilities of macros that questionnaires can make
  126.     use of is the ability to append data to any work file, where work variables
  127.  
  128.  
  129.  
  130.     RBBS-PC QUESTIONNAIRE FACILITIES                                       19-3
  131.  
  132.  
  133.     are merged into a form.   This allows the questionnaire data to be saved in
  134.     virtually any format desired.
  135.  
  136.     The other extremely useful macro capability that questionnaires can utilize
  137.     is the ability to retrieve data from a file into a form, in effect adding a
  138.     data based file retrieval capability.
  139.  
  140.     19.3 Display Data And Get Response
  141.     ----------------------------------
  142.     ?  Question mark (Display data and get response)
  143.        This command is used to send data to the user and wait for a response.
  144.      The user will be required to input a response.  The ENTER key alone  is an
  145.     invalid response.  No other checks are made.
  146.  
  147.               ?DO YOU OWN YOUR OWN PC? (Y/N)
  148.  
  149.     The prompt command accepts an  optional number which is interpreted as  the
  150.     number of the Work Variable to store the answer in.  For example, "
  151.  
  152.               ?8Enter Dept
  153.  
  154.     will store the  answer not only in the regular way  for a questionnaire but
  155.     also in work variable 8.
  156.  
  157.     19.4 Multiple Choice Response
  158.     -----------------------------
  159.     =  Equal sign (Response validation - Multiple choice)
  160.        This  command  is  used  in conjunction  with  the  ?  command  and must
  161.     immediately follow the ? command for which it applies.  This command allows
  162.     for  checking/editing of  single  character responses  to  the preceding  ?
  163.     command and  allows branch  logic to  be exercised  based  on the  response
  164.     given.   Multiple = commands must  be coded on  the same line.   The format
  165.     follows:
  166.  
  167.        =AXXXXXXXXX=BYYYYYYYYY= ZZZZZZZZZZ
  168.  
  169.       =  Indicates that a single character comparison value follows
  170.       A  Is the comparison value
  171.       X  Is the label to branch to if the response is "A"
  172.       =  Indicates that a single character comparison value follows
  173.       B  Is the comparison value
  174.       Y  Is the label to branch to if the response is "B"
  175.       =  Indicates  that a  single character  comparison value  follows (SPACE)
  176.          This is a  special comparison value  that is always  used as the  last
  177.          comparison value and means "INVALID" response given
  178.       Z  Is the label to branch to if an invalid response is given
  179.  
  180.        Maximum line length is 255 characters and the last = on the line "MUST"
  181.        have a comparison value of " " (SPACE).
  182.  
  183.               :QUESTION1
  184.               ?Do you run a BBS system.  (Y/N)
  185.               =YQUESTION2=NQUESTION2= QUESTION1E
  186.               :QUESTION1E
  187.               *Please respond Y or N
  188.               >QUESTION1
  189.               :QUESTION2
  190.  
  191.  
  192.  
  193.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    19-4
  194.  
  195.  
  196.        There is an additional format for the = command, where the comparison
  197.     value of # (Pound  sign) is used.   This is used as a  numeric check and
  198.     encompasses 0-9,  (), - and  space.  This format  requires two entries.
  199.     The first is to  test for numerics and the second is the invalid response
  200.     branch label (e.g. "=#QUESTION3= QUESTION2E").
  201.  
  202.     19.5 Forward And Backward Branching
  203.     -----------------------------------
  204.     >  Greater than sign (Forward and backward branching)
  205.        This  command is used to  branch to specific labels  within the script
  206.     file.
  207.  
  208.               >QUESTION4
  209.  
  210.     19.6 Raise/Lower User's Security Level
  211.     --------------------------------
  212.     +  Plus sign (Raise user security level)
  213.  
  214.     This command  will add the value in  columns 2-6 to the  default security
  215.     level given new users or the current security level of old users.
  216.  
  217.               +5
  218.  
  219.     -  Minus sign (Lower user security level)
  220.  
  221.     This  command will  subtract the  value in  columns 2-6  to the  default
  222.     security given new users or the current security level of old users.
  223.  
  224.               -1
  225.  
  226.     19.7 Abort Questionnaire
  227.     ------------------------
  228.     @  At sign (Abort questionnaire)
  229.  
  230.     This command will terminate the questionnaire and NOT write the response
  231.     to the output file as in the following example.
  232.  
  233.               :QUESTION1
  234.               ?Have you answered the questionnaire before.  (Y/N)
  235.               =YQUESTION2=NQUESTION3= QUESTION1E
  236.               :QUESTION1E
  237.               *Please respond Y or N
  238.               >QUESTION1
  239.               :QUESTION2
  240.               @
  241.               :QUESTION3
  242.  
  243.     19.8 Chain Questionnaire
  244.     ------------------------
  245.     & Ampersand (Chain questionnaire)
  246.  
  247.     This command  will establish the next questionnaire in the chain.  The file
  248.     named  in  columns 2-80  will  be used  as  a continuation  to  the current
  249.     questionnaire when the current questionnaire reaches its last line.
  250.     i.e.   &L:\RBBS\QUESCONT.DEF
  251.  
  252.     19.9 Turbo Keys
  253.     ---------------
  254.     T Turbo Key
  255.  
  256.  
  257.  
  258.     RBBS-PC QUESTIONNAIRE FACILITIES                                       19-5
  259.  
  260.  
  261.     This is used to  turn on Turbo Key for a prompt where a single keystroke is
  262.     expected.  TurboKey  causes the next  keystroke to be  taken as the  answer
  263.     immediately without having to press Enter, if the caller has TurboKey on.
  264.  
  265.     19.10 Macro Execute
  266.     -------------------
  267.     M Macro Execute
  268.  
  269.     This command is used to execute  a specified macro named after the command,
  270.     e.g. "M C:\RBBS\FIZ.IMC".   Control  returns to the  questionnaire after  a
  271.     macro is executed.   One of  the most important capabilities macros add  to
  272.     questionnaires is  the ability  to append  data to any  file in  any format
  273.     desired.   Hence the data in questionnaires can be saved where ever desired
  274.     in whatever format desired.  If a macro saves  the data and you do not want
  275.     the  normal output  on  completion of  the  questionnaire, just  abort  the
  276.     questionnaire at  the end.  Macros  also have the ability  to retrieve data
  277.     from files and then display on the screen.
  278.  
  279.     19.11 Assign Value
  280.     ------------------
  281.     < Macro Assign
  282.  
  283.     This command  assigns a value  to a work  variable.   For example, "<2  XT"
  284.     assigns value "XT" to work variable 2.
  285.  
  286.